[DX-631] Pub/Sub JavaScript SDK API references (realtime interface)#3400
[DX-631] Pub/Sub JavaScript SDK API references (realtime interface)#3400m-hulbert wants to merge 15 commits into
Conversation
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
m-hulbert
force-pushed
the
dx-631-pubsub-js
branch
from
785714e to
5e65a6a
Compare
| @@ -0,0 +1,278 @@ | |||
| --- | |||
| title: Auth | |||
There was a problem hiding this comment.
Just read through the auth page, it's infinitely better than what we originally had! The default values and even some side effects are way easier to understand.
Just a couple of notes that are probably only relevant for this page... "Auth" is both a concept and an interface, so I think we need to be stronger in the intro when framing what is and isn't on this page i.e. I think we should lead with JWTs more strongly and then highlight this page is largely only relevant if you're using the other auth types
|
|
||
| The `Auth` interface is responsible for managing tokens and [authentication](/docs/auth) for an Ably client. Access it via the `auth` property of a [`Realtime`](/docs/pub-sub/api/javascript/realtime/realtime-client) client instance. | ||
|
|
||
| The principal use of `Auth` is to create Ably `TokenRequest`s with `createTokenRequest()`, or to obtain Ably Tokens from Ably with `requestToken()`, and then issue these short-lived tokens to less-trusted clients. Typically, your servers should be the only devices to hold the [private API key](/docs/auth#api-keys), which is used to sign Ably `TokenRequest`s or request Ably Tokens. If you adopt this model, your private API key is never shared with clients directly. |
There was a problem hiding this comment.
TokenRequests formats weirdly... the old prose of "TokenRequest objects" reads nicer
|
|
||
| The `Auth` interface is responsible for managing tokens and [authentication](/docs/auth) for an Ably client. Access it via the `auth` property of a [`Realtime`](/docs/pub-sub/api/javascript/realtime/realtime-client) client instance. | ||
|
|
||
| The principal use of `Auth` is to create Ably `TokenRequest`s with `createTokenRequest()`, or to obtain Ably Tokens from Ably with `requestToken()`, and then issue these short-lived tokens to less-trusted clients. Typically, your servers should be the only devices to hold the [private API key](/docs/auth#api-keys), which is used to sign Ably `TokenRequest`s or request Ably Tokens. If you adopt this model, your private API key is never shared with clients directly. |
There was a problem hiding this comment.
I think the aside is too low down and also doesn't necessarily highlight that this page is largely irrelevant if you do use JWTs...
I think the intro itself could be reframed to something like:
The principal use of Auth is to issue short-lived credentials to less-trusted clients without sharing your private API key. The recommended approach for most applications is Ably JWTs, which let your server mint tokens using standard JWT libraries - examples can be seen here.
Ably also supports signed TokenRequests... blah blah blah... details below
| @@ -0,0 +1,760 @@ | |||
| --- | |||
| title: RealtimeChannel | |||
There was a problem hiding this comment.
The ordering on this page is a little strange imo... I'd expect to see all the channel-centric operations first e.g. attaching, listeners, etc.. first, followed by all the message operations e.g. history, append, etc...
3 participants
Description
This PR proposes a new format for the Pub/Sub JavaScript SDK (realtime interface) API references.
It uses the new components and design for API references introduced for the Chat API refs, updates the content to the latest SDK version (2.22.1) and tidies up anything that was legacy.
It also introduces a slightly new IA to better group like APIs, and ensures a better blend between the actual interface names used by the SDK (e.g.
RealtimeChannel) and the concepts themselves (e.g. 'Channels').For now, this doesn't update any links or remove the existing API references. This will follow once REST is complete for JavaScript, as we'll need to update the query param behaviour for API reference links. 1
Checklist